---
title: 部署你的 Astro 站点至 Cloudflare
description: 如何使用 Cloudflare 将你的 Astro 网站部署到网络上
sidebar:
  label: Cloudflare
type: deploy
logo: cloudflare
supports: ['ssr', 'static']
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
import StaticSsrTabs from '~/components/tabs/StaticSsrTabs.astro';

你可以通过 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/) 和 [Cloudflare Pages](https://pages.cloudflare.com/) 来部署全栈应用，包括前端的静态资源和后端的 API，以及按需渲染站点。

本指南包含：

- [如何部署至 Cloudflare Workers](#cloudflare-workers)
- [如何部署至 Cloudflare Pages](#cloudflare-pages)

:::note

Cloudflare 更建议为新项目使用 Cloudflare Workers。对于现有的、使用 Pages 的项目，可参考 [Cloudflare 的迁移指南](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) 以及 [compatibility matrix](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/#compatibility-matrix)。

:::

<ReadMore>阅读有关在 Astro 项目中 [使用 Cloudflare 运行时](/zh-cn/guides/integrations-guide/cloudflare/) 的更多内容。</ReadMore>

## 前提条件

开始之前，你需要：

- 一个 Cloudflare 账号。如果你暂时还没有，可通过 Cloudflare 官网免费注册。

## Cloudflare Workers

### 如何使用 Wrangler 进行部署

<Steps>
1. 安装 [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)。

    ```bash
    npm install wrangler@latest --save-dev
    ```

2. 如果你的站点使用了按需渲染，安装 [`@astrojs/cloudflare` 适配器](/zh-cn/guides/integrations-guide/cloudflare/)。

    该步骤将会安装适配器，并对你的 `astro.config.mjs` 文件进行适当的调整。
    
      ```bash
      npx astro add cloudflare
      ```
      
      接下来，在你的 `public/` 文件夹中创建一个 `.assetsignore` 文件，并向其添加以下内容：
      ```txt title="public/.assetsignore"
      _worker.js
      _routes.json
      ```
  
    <ReadMore>阅读更多有关 [Astro 中的按需渲染](/zh-cn/guides/on-demand-rendering/)的内容。</ReadMore>

3. 创建一个 [Wrangler 配置项文件](https://developers.cloudflare.com/workers/wrangler/configuration/)。

    <StaticSsrTabs>
      <Fragment slot="static">
        ```jsonc
        // wrangler.jsonc
        {
          "$schema": "node_modules/wrangler/config-schema.json",
          "name": "my-astro-app",
          // 更新为今天的日期
          "compatibility_date": "2025-03-25",
          "assets": {
            "directory": "./dist",
            "not_found_handling": "404-page" // 如果你有自定义的 `src/pages/404.astro` 页面
          }
        }
        ```
      </Fragment>
      <Fragment slot="ssr">
        ```jsonc
        // wrangler.jsonc
        {
          "$schema": "node_modules/wrangler/config-schema.json",
          "name": "my-astro-app",
          "main": "./dist/_worker.js/index.js",
          // 更新为今天的日期
          "compatibility_date": "2025-03-25",
          "compatibility_flags": ["nodejs_compat"],
          "assets": {
            "binding": "ASSETS",
            "directory": "./dist"
          },
          "observability": {
            "enabled": true
          }
        }
    ```
      </Fragment>
    </StaticSsrTabs>

4. 使用 Wrangler 对你的项目进行本地预览。

    ```bash
    npx astro build && npx wrangler dev
    ```

5. 使用 `npx wrangler deploy` 命令进行部署。

    ```bash
    npx astro build && npx wrangler deploy
    ```
</Steps>

在你的资源上传之后，Wrangler 将会提供一个预览 URL 用以让你检视自己的网站。

<ReadMore>阅读更多有关使用 [Cloudflare 运行时 API](/zh-cn/guides/integrations-guide/cloudflare/) 的内容，例如绑定。</ReadMore>

### 如何使用 CI/CD 进行部署

你可以使用一个 CI/CD 系统，例如 [Workers Builds (BETA)](https://developers.cloudflare.com/workers/ci-cd/builds/) 来通过推送，自动化构建并部署你的网站。

假设你正在使用 Workers Builds：

<Steps>
1. 与上文中如何使用 Wrangler 进行部署的步骤 1-3 相同。

2. 登录至 [Cloudflare dashboard](https://dash.cloudflare.com/) 并导航至 `Workers & Pages` 页面。选择 `Create`（创建）。

3. 在 `Import a repository`（导入仓库）选项下，选择一个 Git 账号，然后选择包含你 Astro 项目的仓库。

4. 配置项目：
    - Build command（构建命令）：`npx astro build`
    - Deploy command（部署命令）：`npx wrangler deploy`
    
5. 点击 `Save and Deploy`（保存并部署）。你现在可以在它提供的 `workers.dev` 子域名下，预览 Worker 部署的结果了。
</Steps>

## Cloudflare Pages

### 如何使用 Wrangler 进行部署

<Steps>
1. 安装 [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/)。

    ```bash
    npm install wrangler@latest --save-dev
    ```

2. 如果你的站点使用了按需渲染，安装 [`@astrojs/cloudflare` 适配器](/zh-cn/guides/integrations-guide/cloudflare/)。
    
    该步骤将会安装适配器，并对你的 `astro.config.mjs` 文件进行适当的调整。
    
      ```bash
      npx astro add cloudflare
      ```
      
    <ReadMore>阅读更多有关 [Astro 中的按需渲染](/zh-cn/guides/on-demand-rendering/) 的内容。</ReadMore>

3. 使用 Wrangler 对你的项目进行本地预览。

    ```bash
    npx astro build && npx wrangler pages dev ./dist
    ```

4. 使用 `npx wrangler deploy` 命令进行部署。

    ```bash
    npx astro build && npx wrangler pages deploy ./dist
    ```
</Steps>

在你的资源上传之后，Wrangler 将会提供一个预览 URL 用以让你检视自己的网站。

### 如何使用 Git 来部署站点

<Steps>
1. 推送代码至 Git 仓库（例如：GitHub、GitLab）。

2. 登录至 [Cloudflare dashboard](https://dash.cloudflare.com/) 并导航至 **Compute (Workers) > Workers & Pages**。选择 **Create**（创建）并选择 **Pages**（页面）标签页。连接至你的 Git 仓库。

3. 配置项目：
    - **Framework preset（框架预设）**：`Astro`
    - **Build command（构建命令）**：`npm run build`
    - **Build output directory（构建输出目录）**：`dist`

4. 点击 **Save and Deploy（保存并部署）** 按钮。
</Steps>

## 故障排除

### 客户端 hydration

由于 Cloudflare 的 Auto Minify（自动压缩）功能，客户端 Hydration 可能会失败。如果你在控制台中看到 `Hydration completed but contains mismatches`，请确保在 Cloudflare 设置中禁用 Auto Minify。

### Node.js 运行时 API

如果你正在构建一个使用 [Cloudflare 适配器](/zh-cn/guides/integrations-guide/cloudflare/) 的按需渲染项目，并且服务器在构建时失败，出现如 `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.` 的错误信息：

- 这意味着你在服务器端环境中使用的某个包或导入项与 [Cloudflare 运行时 API](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) 不兼容。

- 如果你直接导入了一个 Node.js 运行时 API，请参考 Astro 关于 Cloudflare 的 [Node.js 兼容性](/zh-cn/guides/integrations-guide/cloudflare/#nodejs-兼容性) 文档，了解如何解决这个问题的进一步步骤。

- 如果你导入的包中包含了 Node.js 运行时 API，请检查该包的作者是否支持 `node:*` 的导入语法。如果不支持，你可能需要找到一个替代的包。
